Enterprise Objects Framework Release 1.1 Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

EOController

Inherits From:	NSObject

Declared In:	eointerface/EOController.h

Class Description

An EOController synchronizes a set of data-bearing enterprise objects with user interface objects; the interface objects display values for properties of the enterprise objects, and the controller processes changes to those values from the interface objects. The objects an EOController manages are received from a data source object. A data source is any object that conforms to the EODataSources protocol, which defines methods for fetching objects from storage, inserting objects into and deleting them from storage, and for changing the properties of existing objects. A data source can also conform to the EOMasterDataSources and EOQualifiableDataSources protocols, allowing it to participate in master-detail relationships, and the EORollbackDataSources protocol, allowing it to roll back changes.

The Enterprise Objects Framework provides two data source classes: EODatabaseDataSource and EODetailDatabaseDataSource. These classes provide objects for a single entity in the application's model, and also conform to the EOMasterDataSources, EOQualifiableDataSources, and EORollbackDataSources protocols.

EOController presents its enterprise objects as an NSArray, and identifies them solely by index in that array. An EOController also maintains a selection in the form of a set of indexes. You can insert, delete, or update an object at a particular index or can apply an operation to all selected objects.

Associations

An EOController communicates with user interface objects through EOAssociation objects. An association links a single, named property of the controller's enterprise objects to a user interface object, such as a TextField or NXTableView. The association is responsible for monitoring the user interface object, notifying the controller when the selection changes or when the user interface object is edited, and updating the user interface object to reflect the values of the controller's enterprise objects.

You can create most associations in Interface Builder, but if you need to set one up programmatically you can usually follow this template:

EOController *myController;  /* Assume this exists. */
id myUIObject;               /* Assume this exists. */
Class assocClass;
EOAssociation *myAssociation;

assocClass = [myUIObject associationClass];
myAssociation = [[assocClass alloc] initWithController:myController
    key:@"propertyName"
    destination:myUIObject];

[myController addAssociation:myAssociation];

This code excerpt assumes no knowledge about association subclasses; it sends associationClass to the user interface object to get a default class for associations, then creates the association to monitor the property named ªpropertyNameº. (You may want to confirm that the user interface object responds to associationClass before sending it.) Finally, it adds the association to the set managed by the controller with addAssociation:.

Note:  This approach doesn't work for an NXTableView. Its association class, EOColumnAssociation, requires special handling. See the EOColumnAssociation class specification for more information.

If you have a special association class designed to work with a user interface object, you can explicitly create an instance of that class instead of asking the user interface object for its default association class. associationClass is simply a mechanism for dynamically selecting an appropriate association for a given user interface object.

An association forms an intimate link with its user interface object. It nearly always sets itself up as a control's target, and often sets itself up as the text delegate of its user interface object as well. You should assume that a user interface object managed by an association is off-limits with regard to changing its state, and handle all data manipulation and validation in the controller's delegate or in the enterprise objects themselves (note that a custom association can also handle validation).

A slightly different type of association is that between two EOControllers. An EOQualifiedAssociation links two controllers in a master-detail relationship, so that when the object selected in the master controller changes, the detail controller's data source is configured to provide objects related to the one selected in the master.

Master-detail Controllers and the Controller Chain

Controllers linked in a master-detail relationship are treated specially. When an EOController performs a fetch, saveToObjects, saveToDataSource, or redisplay message, it checks the destination of each of its associations to see if that object is also an EOController. If so, it propagates the operation to them, thus synchronizing the state and display of all linked controllers.

If you don't want to set up a pair of controllers in a master-detail relationship, you can still have one of them propagate the methods listed above by using the setNextController: message or connecting the two controllers in Interface Builder. Linking controllers together in this manner allows the otherwise independent controllers, each managing their own sets of enterprise objects, to remain synchronized with respect to all significant operations. You can link any number of controllers together in this fashion, but you should be aware that the four actions are propagated down the chain only; controllers above the one that receives the original message aren't notified (unless the chain is a loop, which is permitted).

Buffering and Undo

EOController offers two levels of change buffering and a powerful undo mechanism. There are two kinds of changes: edits to the values of enterprise objects, and operations on the enterprise objects in the data source (insertion, deletion, and update with buffered edits). When a controller is buffering edits, it saves each change sent by its association objects. It doesn't apply these changes to its enterprise objects until it receives a saveToObjects message. Similarly, operations on the objects held by the controller aren't applied to the data source until the controller receives a saveToDataSource message.

You can remove buffering so that changes are immediately saved by sending a controller a setSavesToObjectsAutomatically: or setSavesToDataSourceAutomatically: message. This table shows how automatic saving affects the state of the controller's enterprise objects and data source:

Saves automatically to:
Objects	Data Source	Behavior

YES	YES	All changes are immediately sent to the controller's data source. This is the default behavior for controllers created in Interface Builder.

YES	NO	Edits immediately go to enterprise objects; you must send saveToDataSource to send changes to the data source.

NO	YES	Edits are buffered, but when you send saveToObjects changes are immediately sent to the data source.

NO	NO	You must send saveToObjects to effect changes to enterprise objects, then send saveToDataSource to send the changes to the data source. This is the default behavior for controllers created programmatically.

In addition to buffering changes, an EOController maintains an undo stack that records those changes after they've been applied. You can send a controller a markUndo message at any time to mark the current point on the undo stack. A later undo message reverts the changes in the undo stack back to that point: deleted objects are recovered, inserted objects are deleted, and all editsÐpending and savedÐare undone. You can configure an EOController to automatically mark an undo point after every operation, or you can manually control undo marks to group operations together so that they can all be undone with a single undo message. To find out if a given EOController has edits on its undo stack, send the controller hasUndos.

For more information on data sources, see the EODataSources and EOQualifiableDataSources protocol specifications.

Notifying the Controller's Delegate

An EOController notifies its delegate of nearly every operation it performs. It confirms any insertion, deletion, or update with its delegate before performing the operation, and notifies the delegate of undo and save operations, and of any change in selection. Further, if a change to the data source fails for any reason, the delegate has a chance to tell the controller whether to simply continue or to roll back changes (if the data source supports rollback).

All a delegate need do to receive a notification from its controller is implement the appropriate methods. These methods are documented after EOController's class and instance methods, under ªMethods Implemented by the Delegate.º If the delegate doesn't implement a particular method, it isn't invoked.

Instance Variables

None declared in this class.

Method Types

Initializing an EOController	- initWithDataSource:

Managing associations	- addAssociation:
- associations
- disableAssociationNotification
- keys
- reenableAssociationNotification
- removeAssociation:

Getting the objects	- allObjects

Fetching objects	- fetch

Managing the selection	- setSelectionIndexes:
- selectionIndexes
- selectedObjects
- clearSelection
- selectNext
- selectPrevious
- setSelectsFirstObjectAfterFetch:
- selectsFirstObjectAfterFetch

Editing objects	- associationDidEdit:
- setValues:forObject:
- endEditing

Sorting objects	- resort
- setSortOrdering:
- sortOrdering

Performing operations on objects
- deleteObjectAtIndex:
- deleteSelection
- insertObjectAtIndex:
- insertObject:atIndex:

Discarding changes	- discardEdits
- discardOperations
- isDiscardAllowed

Saving edits to objects	- saveToObjects
- hasChangesForObjects
- setSavesToObjectsAutomatically:
- savesToObjectsAutomatically

Saving to the data source	- saveToDataSource
- hasChangesForDataSource
- setSavesToDataSourceAutomatically:
- savesToDataSourceAutomatically

Controlling undo	- hasUndos
- setUndoEnabled:
- isUndoEnabled
- markUndo
- undo
- releaseUndos
- setMarksEveryOperation:
- marksEveryOperation
- setMaximumUndoMarks:
- maximumUndoMarks

Redisplaying the user interface	- redisplay

Chaining controllers	- setNextController:
- nextController

Setting the data source	- setDataSource:
- dataSource

Setting the delegate	- setDelegate:
- delegate

Action methods	- delete:
- discardEdits:
- discardOperations:
- fetch:
- insert:
- markUndo:
- saveToDataSource:
- saveToObjects:
- selectNext:
- selectPrevious:
- undo:

Instance Methods

addAssociation:

- (void)addAssociation:(EOAssociation *)anAssociation

Adds anAssociation to the set managed by the controller.

See also:  - removeAssociation:, - associations

allObjects

- (NSArray *)allObjects

Returns all enterprise objects accessible through the controller.

See also:  - selectedObjects

associationDidEdit:

- (void)associationDidEdit:(EOAssociation *)anAssociation

Informs the controller that anAssociation has a pending edit. The controller gets anAssociation's key and value and adds the new value to its edit buffer.

If the controller is configured to save changes automatically then the changes are immediately saved to the objects. If the controller doesn't save changes automatically, the changes don't take effect until the controller receives a saveToObjects message.

This method invokes the delegate method controller:association:didEditObject:key:value:.

See also:  - key (EOAssociation), - value (EOAssociation), - savesToObjectsAutomatically, - savesToDataSourceAutomatically

associations

- (NSArray *)associations

Returns the controller's associations.

clearSelection

- (BOOL)clearSelection

Empties the controller's selection. This method is a shortcut for sending setSelection: with an empty array. Doesn't redisplay the user interface objects. Returns YES if successful, NO if not.

See also:  - redisplay

dataSource

- (id <EODataSources>)dataSource

Returns the controller's data source.

delegate

- delegate

Returns the controller's delegate.

delete:

- delete:sender

This action method invokes deleteSelection to delete all selected objects. Returns self if deleteSelection returns YES, nil if it returns NO.

deleteObjectAtIndex:

- (BOOL)deleteObjectAtIndex:(unsigned int)anIndex

Deletes the object at anIndex, pending approval by the delegate. Returns YES if the object is actually deleted, NO otherwise.

If the data source can't delete, this method opens an attention panel notifying the user and returns NO. If the data source can delete, invokes endEditing and notifies the delegate with controller:willDelete:Object:. If the delegate approves, deletes the object and notifies the delegate with controller:didDeleteObject: and the controller's associations with contentsDidChange and selectionDidChange.

Deletion is an operation applied immediately to the object; you don't need to send saveToObjects. If the controller is configured to save to the data source automatically then the changes are immediately made to the data source as well. If the controller doesn't save changes automatically, the changes don't take effect in the data source until the controller receives a saveToDataSource message.

See also:  - delete:, - deleteSelection, - savesToDataSourceAutomatically

deleteSelection

- (BOOL)deleteSelection

Deletes all objects in the selection in the manner described for deleteObjectAtIndex: (including invocation of delegate methods). Returns YES if all objects in the selection were successfully deleted (or if there were no objects selected), NO otherwise. If this method returns NO it's possible that only some objects in the selection have been deleted.

Deleting the selection is considered a single operation for purposes of undo, even if the controller marks every operation.

See also:  - delete:

disableAssociationNotification

- (void)disableAssociationNotification

Allows you to specify that EOAssociationNotification messages should not be sent (they are sent by default).  For each disableAssociationNotification, you should send a corresponding reenableAssociationNotification.

- reenableAssociationNotification

discardEdits

- (void)discardEdits

Clears all edits pending in the controller, and also in user interface objects (by sending discardEdits to all of the controller's associations). This method is only useful if the controller isn't configured to save to objects automatically.

See also:  - savesToObjectsAutomatically

discardEdits:

- discardEdits:sender

This action method invokes discardEdits and returns self.

discardOperations

- (void)discardOperations

Clears all pending operations. This method is only useful if the controller isn't configured to save to the data source automatically.

See also:  - savesToDataSourceAutomatically

discardOperations:

- discardOperations:sender

This action method invokes discardOperations and returns self.

endEditing

- (void)endEditing

Sends endEditing to each of the controller's associations. This method is invoked whenever the controller needs to force an end to editing in the user interface objects, which is whenever:

·	The controller fetches.
·	The controller saves changes to its objects or to its data source.
·	An object is inserted or deleted.
·	The selection changes.
·	The undo stack is altered by a markUndo, undo, or releaseUndos message.

See also:  - endEditing (EOAssociationNotification protocol)

fetch

- (BOOL)fetch

Fetches objects from the controller's data source, returning YES if successful, NO if not.

The controller first invokes endEditing. Next, it sends controllerWillFetch: to its delegate, aborting the fetch and returning NO if the delegate returns NO. If the delegate returns YES, the controller then confirms that pending changes can be discarded by invoking isDiscardAllowed (it also confirms that any detail or linked controllers allow pending changes to be discarded). The controller aborts the fetch and returns NO if isDiscardAllowed returns NO or if any of the detail or linked controllers don't allow discard.

After confirming that changes can be discarded, the controller discards all edits and operations, and clears the undo stack. The controller then sends fetchObjects to its data source, and resynchronizes its selection with the new objects.

After fetching objects, the controller sends controllerDidFetchObjects: to its delegate and contentsDidChange to its associations. If the controller's selection changed as a result of fetching, also sends selectionDidChange to the associations. Finally, the controller propagates the fetch message to all detail and linked controllers.

See also:  - discardEdits, - releaseUndos, - selectsFirstObjectAfterFetch

fetch:

- fetch:sender

This action method invokes fetch and returns self if fetch returns YES, nil if it returns NO.

hasChangesForDataSource

- (BOOL)hasChangesForDataSource

Returns YES if there are any operations buffered for the data source, NO otherwise.

See also:  - savesToDataSourceAutomatically, - hasChangesForObjects, - saveToObjects

hasChangesForObjects

- (BOOL)hasChangesForObjects

Returns YES if any object has been edited since the last saveToObjects message, NO otherwise.

See also:  - savesToObjectsAutomatically, - hasChangesForDataSource, - associationDidEdit:, - setValues:forObject:

hasUndos

- (BOOL)hasUndos

Returns YES if the controller has any entries on its undo stack.

initWithDataSource:

- initWithDataSource:(id <EODataSources>)aDataSource

Initializes a newly allocated EOController to get its data from objects provided by aDataSource. This is the designated initializer for the EOController class. Returns self.

insert:

- insert:sender

This action method uses insertObjectAtIndex: to insert a new object after the selected object, or if nothing is selected, at the end of the array. Returns self, or nil if insertObjectAtIndex: returns nil.

insertObjectAtIndex:

- insertObjectAtIndex:(unsigned int)anIndex

Inserts and selects a new object, created by the controller's data source, at anIndex by invoking insertObject:atIndex:. Invokes endEditing before performing the insertion. Returns the object that was inserted, or nil on failure.

Note:  You must set the new object's primary key before saving to the data source. If the controller is configured to save automatically to the data source you shouldn't use this method.

Raises NSRangeException if anIndex indicates a position past the end of the controller's array of objects.

See also:  - createObject (EODataSources protocol of the access layer)

insertObject:atIndex:

- insertObject:anEO atIndex:(unsigned int)anIndex

Inserts anEO at anIndex in the array of enterprise objects managed by the controller. Invokes endEditing before performing the insertion. Returns the object that was inserted, or nil on failure. Raises NSRangeException if anIndex indicates a position past the end of the controller's array of objects.

Insertion is an operation applied immediately to the object; you don't need to send saveToObjects. If the controller is configured to save to the data source automatically then the changes are immediately made to the data source as well. If the controller doesn't save changes automatically, the changes don't take effect in the data source until the controller receives a saveToDataSource message.

Note:  You must set anEO's primary key before saving to the data source. If the controller is configured to save to the data source anEO must already have its primary key set when you insert it.

After inserting the object the controller selects it and sends contentsDidChange and selectionDidChange to all of its associations.

This method invokes the delegate methods controller:willInsertObject:, controller:didInsertObject:, and controller:failedToInsertObject:. See the descriptions for these methods for information on how they affect insertion.

See also:  - insert:, - savesToDataSourceAutomatically

isDiscardAllowed

- (BOOL)isDiscardAllowed

Verifies that discarding of edits not saved to objects and updates not saved to the data source is allowed. Returns YES if discarding of edits and updates is allowed, NO if not. A controller uses this method when fetching and changing the selection, to make sure that an operation doesn't inadvertently discard pending changes.

If the controller has any pending edits, it sends controllerWillDiscardEdits: to the delegate. If the delegate returns NO, this method immediately returns NO. If the delegate returns YES, this method continues by checking whether operations may be discarded. If the delegate doesn't implement controllerWillDiscardEdits:, the controller opens an attention panel asking the user if it's okay to discard edits. The panel offers the user the choice to save the edits (causing saveToObjects to be invoked), to cancel whatever operation invoked this method, or to allow edits to be discarded; if the user chooses to save edits or to cancel, this method returns NO.

Next, if there are any operations not saved to the data source the controller sends controllerWillDiscardOperations: to the delegate. Again, if the delegate doesn't implement this method the controller opens an attention panel asking the user to save, cancel, or allow discard of operations; if the user chooses to save operations or to cancel, this method returns NO. Finally, if all of these conditions are passed, this method returns YES.

See also:  - discardEdits, - saveToObjects, - saveToDataSource

isUndoEnabled

- (BOOL)isUndoEnabled

Returns YES if undo is enabled, NO otherwise. Undo is by default not enabled for controllers created programmatically, though it is for controllers created in Interface Builder.

keys

- (NSArray *)keys

Returns the keys used by the controller's associations (which aren't necessarily all the keys used by its enterprise objects). These keys are the names of properties of the controller's enterprise objects, as used in the EOKeyValueCoding informal protocol defined by the access layer. There may be duplicate keys in the returned array.

See also:  - key (EOAssociation)

markUndo

- (void)markUndo

Ends editing and marks the current state of the undo stack as an undo point. An undo message reverts changes made since the last undo point marked. This method does nothing if undo isn't enabled or if a mark is already set on the top of undo stack.

See also:  - isUndoEnabled, - releaseUndos, - endEditing

markUndo:

- markUndo:sender

This action method invokes markUndo and returns self.

marksEveryOperation

- (BOOL)marksEveryOperation

Returns YES if an undo point is marked upon every insertion, deletion, and application of edits to an enterprise object, NO otherwise. Controllers created programmatically by default don't mark every operation, while those created in Interface Builder do.

See also:  - deleteSelection

maximumUndoMarks

- (unsigned int)maximumUndoMarks

Returns the maximum number of undo marks the controller will record. Marks added beyond this limit cause earlier marks to fall off the queue. This method is useful for restricting memory usage. The default maximum is zero, which actually indicates no limit.

See also:  - isUndoEnabled

nextController

- (EOController *)nextController

Returns the next controller in the controller chain. See the class description for information on the controller chain.

redisplay

- (void)redisplay

Sends contentsDidChange to all the controller's associations, causing them to redisplay their user interface items as needed. Also has the controller's detail controllers and next controller redisplay.

See also:  - nextController

reenableAssociationNotification

- (void)reenableAssociationNotification

Allows you to specify that EOAssociationNotification messages should be sent (they are sent by default), countering a disableAssociationNotification message.  For each disableAssociationNotification, you should send a corresponding reenableAssociationNotification. The final call to reenableAssociationNotification does not flush pending notifications to the associations; [controller redisplay] must be explicitly called, if needed.

- disableAssociationNotification

releaseUndos

- (void)releaseUndos

Clears all undo information. No undo is possible until a new undo point is established, either automatically or with markUndo.

See also:  - marksEveryOperation

removeAssociation:

- (void)removeAssociation:(EOAssociation *)anAssociation

Removes anAssociation from the set managed by the controller.

See also:  - addAssociation:

resort

- (void)resort

forces the object array to be sorted and redisplayed. Note that the object array is automatically sorted after a fetch.

See also:  - setSortOrdering:

savesToDataSourceAutomatically

- (BOOL)savesToDataSourceAutomatically

Returns YES if saving to objects, or inserting or deleting an object, results in the controller performing saveToDataSource, NO if it doesn't. Controllers created programmatically by default don't save automatically, but those created in Interface Builder do.

See also:  - saveToObjects, - savesToObjectsAutomatically

savesToObjectsAutomatically

- (BOOL)savesToObjectsAutomatically

Returns YES if the controller immediately performs saveToObjects when an association notifies it of an edit or when an object is edited with setValues:forObject:. Returns NO otherwise. Controllers created programmatically by default don't save automatically, but those created in Interface Builder do.

See also:  - associationDidEdit:, - savesToDataSourceAutomatically

saveToDataSource

- (BOOL)saveToDataSource

Ends editing and saves all pending operations for the controller itself, for its detail controllers, and for its next controller. If none of the controllers has saved edits to their objects, this method has no effect; use saveToObjects to make sure pending edits are applied to the objects before invoking saveToDataSource. Returns YES if all changes are successfully saved to the data source, NO if any save operation fails or is refused by the delegate. If this method returns NO and the controller's data source doesn't support rolling back operations, some changes may have been saved anyway.

In saving an object, the controller sends it a prepareForDataSource message (if it responds). If the object returns NO the controller sends its delegate a controller:object:failedToPrepareForDataSource: message. If the delegate returns EOContinueDataSourceFailureResponse the controller continues saving the remaining objects. If the delegate returns EORollbackDataSourceFailureResponse or doesn't implement the delegate method, the controller rolls back all operationsÐif the data source supports rollbackÐand returns NO.

If the object returns YES from prepareForDataSource, then the controller checks with its delegate for each operation to save and sends insertObject:, deleteObject:, or updateObject: to the data source depending on the change to be saved. If any of these messages fails, this method informs the delegate, stops saving, and returns NO.

This method may invoke any of the delegate methods listed below, depending on the individual save operations being performed. See the descriptions of the individual methods for more information on how they interact with saveToDataSource.

controller:object:failedToPrepareForDataSource:

controllerWillSaveToDataSource:
controllerDidSaveToDataSource:

controller:willRollbackDataSource:
controller:didRollbackDataSource:

controller:willInsertObject:inDataSource:
controller:didInsertObject:inDataSource:
controller:failedToInsertObject:inDataSource:

controller:willDeleteObject:inDataSource:
controller:didDeleteObject:inDataSource:
controller:failedToDeleteObject:inDataSource:

controller:willUpdateObject:inDataSource:
controller:didUpdateObject:inDataSource:
controller:failedToUpdateObject:inDataSource:

See also:  - insertObjectAtIndex:, - deleteObjectAtIndex:, - endEditing

saveToDataSource:

- saveToDataSource:sender

This action method invokes saveToDataSource, returning self if saveToDataSource returns YES, nil if it returns NO.

saveToObjects

- (BOOL)saveToObjects

Ends editing and saves all edits made to objects as operations to apply to the controller's data source. Returns YES if all changes are successfully saved to the controller's objects, NO if any save operation fails or is refused by the delegate. If this method returns NO some changes may have been saved while others may not.

In saving a set of edits to an enterprise object, the controller first confirms the action with its delegate by sending it a controller:willSaveEdits:toObject: message; if the delegate returns nil the controller aborts the save operation and returns NO. The controller takes a non-nil return value from this message and converts the new values by sending coerceValue:forKey: to its data source. It then applies the converted values to the enterprise object by sending the enterprise object a takeValuesFromDictionary: message (a method of the access layer's EOKeyValueCoding informal protocol). After saving each object the controller sends controller:didSaveToObject: to its delegate.

If the controller saves to the data source automatically then the each saved edit is immediately applied to the data source. If the controller doesn't save changes automatically, the changes don't affect the data source until the controller receives a saveToDataSource message.

Finally, after saving all edits the controller sends contentsDidChange and discardEdits to its associations. If all of the changes were successfully saved, the controller has its detail controllers and next controller save to objects as well.

See also:  - associationDidEdit:, - setValues:forObject:, - saveToDataSource, - endEditing

saveToObjects:

- saveToObjects:sender

This action method invokes saveToObjects, returning self if saveToObjects returns YES, nil if it returns NO.

selectNext

- (BOOL)selectNext

Selects the object after the currently selected object. If no objects are selected or if the last object is selected, then the first object becomes selected. If multiple objects are selected, this method selects the object after the first object in the selection. This method results in a setSelectionIndexes: message being sent, and returns the value returned by that message.

This method is useful for user interfaces that display only one object at a time.

See also:  - selectNext:

selectNext:

- selectNext:sender

This action method invokes selectNext, returning self if selectNext returns YES, nil if it returns NO.

selectPrevious

- (BOOL)selectPrevious

Selects the object before the currently selected object. If no objects are selected then the first object becomes selected. If the first object is selected then the last object becomes selected. If multiple objects are selected, this method selects the object before the first object in the selection. This method results in a setSelectionIndexes: message being sent, and returns the value returned by that message.

This method is useful for user interfaces that display only one object at a time.

See also:  - selectPrevious:

selectPrevious:

- selectPrevious:sender

This action method invokes selectPrevious, returning self if selectPrevious returns YES, nil if it returns NO.

selectedObjects

- (NSArray *)selectedObjects

Returns the selected objects.

See also:  - selectionIndexes

selectionIndexes

- (NSArray *)selectionIndexes

Returns an array of NSNumber objects identifying the indexes of the selected objects in the controller's array of objects.

See also:  - selectedObjects, - allObjects

selectsFirstObjectAfterFetch

- (BOOL)selectsFirstObjectAfterFetch

Returns YES if the controller selects the first of its objects after performing a fetch, NO if not.

See also:  - setSelectionIndexes:

setDataSource:

- (void)setDataSource:(id <EODataSources>)aDataSource

Sets the controller's data source to aDataSource, clears the selection and the undo stack, and discards all pending changes. This method invokes the delegate method controller:didChangeDataSource:.

See also:  - releaseUndos, - discardEdits, - clearSelection

setDelegate:

- (void)setDelegate:anObject

Sets the controller's delegate to anObject. Doesn't retain anObject.

setMarksEveryOperation:

- (void)setMarksEveryOperation:(BOOL)flag

Sets according to flag whether the controller marks an undo point for every insertion, deletion, or edit of an object. Controllers created programmatically don't mark every operation by default, while those created in Interface Builder do.

See also:  - markUndo, - deleteSelection

setMaximumUndoMarks:

- (void)setMaximumUndoMarks:(unsigned int)anInt

Sets to anInt the maximum number of undo marks that will be recorded. Marks added after the maximum amount will causes earlier marks to be discarded. This method is useful for restricting memory usage. Setting the maximum to 0 allows unlimited undo queueing; this is the default. Use setUndoEnabled: to disable undo.

See also:  - undo

setNextController:

- setNextController:(EOController *)aController

Sets the next controller in the controller chain to aController. See the class description for information on the controller chain.

setSavesToDataSourceAutomatically:

- (BOOL)setSavesToDataSourceAutomatically:(BOOL)flag

Sets according to flag whether operations such as insert, delete, and update with edits automatically result in the controller performing saveToDataSource. Returns YES if successful, NO if the controller has any pending operations for its data source.

Controllers created programmatically don't save automatically by default, but those created in Interface Builder do.

See also:  - setSavesToObjectsAutomatically:

setSavesToObjectsAutomatically:

- (BOOL)setSavesToObjectsAutomatically:(BOOL)flag

Sets according to flag whether the controller immediately performs saveToObjects when an object is edited. Returns YES if successful, NO if the controller has any pending edits for its objects.

Controllers created programmatically don't save automatically by default, but those created in Interface Builder do.

See also:  - setSavesToDataSourceAutomatically:, - associationDidEdit:, - setValues:forObject:

setSelectionIndexes:

- (BOOL)setSelectionIndexes:(NSArray *)aSelection

Sets the selection as an array of NSNumber objects. Returns YES if the selection is changed to aSelection, NO if not.

The controller recursively sends isDiscardAllowed to all of its detail controllers, and if any of them returns NO the selection isn't changed. If the detail controllers allow discard this method invokes endEditing, sets the selection indexes, and notifies its associations with selectionDidChange. Finally, this method sends controllerDidChangeSelection: to the delegate.

If an association attempts to change the selection of its controller and fails, the association should reset the selection of its user interface object from the controller's selection. It can do this by simply sending itself a selectionDidChange method.

setSelectsFirstObjectAfterFetch:

- (void)setSelectsFirstObjectAfterFetch:(BOOL)flag

Sets according to flag whether the controller selects the first of its objects after performing a fetch.

See also:  - setSelectionIndexes:

setSortOrdering:

- (void)setSortOrdering:(NSArray *)keySortOrderArray

Sets an EOKeySortOrder array to be applied to all records upon a fetch or resort. 

See also:  - sortOrdering, - resort

setUndoEnabled:

- (void)setUndoEnabled:(BOOL)flag

Enables or disables undo according to flag. Undo is by default not enabled for controllers created programmatically, though it is for controllers created in Interface Builder.

This method doesn't affect existing undo marks. You can temporarily disable undo, then reenable it and perform an undo; however, any changes made while undo was disabled won't be reverted.

setValues:forObject:

- (void)setValues:(NSDictionary *)newValues forObject:anEO

Applies newValues to anEO as if they were edits made by an association. If the controller doesn't save automatically to objects, the new values are buffered as edits that will actually be sent to anEO upon the next saveToObjects message. If the controller saves automatically to objects then the changes are immediately saved to the objects.

The controller's associations are not notified when an edit is made with this method. You should send the controller a redisplay message after you finish editing objects programmatically to update the user interface.

See also:  - associationDidEdit:, - savesToObjectsAutomatically

sortOrdering

(NSArray *)sortOrdering

Returns the EOKeySortOrder array that is used to sort all records upon a fetch or resort.

- setSortOrdering:, - resort

undo

- (void)undo

Reverts all changes in the undo stack to the last undo mark set; inserted objects are removed, deleted objects restored, and any edits are reversed. If there are no undo marks set, does nothing.

This method first invokes saveToObjects to accumulate all changes in the operation buffer, from which they're reverted. If the user is editing a value and the controller marks every operation, this results in the undo operation naturally reverting just the edit in progress.

The controller notifies its delegate before reverting changes with a controllerWillUndo: message; if the delegate returns NO the undo operation is aborted. Similarly, for each change reverted the controller sends its delegate a controller:willUndoObject: message; if the delegate returns NO then the undo for that object is skipped but the undo operation continues. After the change is reverted the controller sends controller:didUndoObject: to its delegate. Finally, after all changes have been reverted, the controller sends controllerDidUndo: to its delegate and contentsDidChange to its associations. If the controller's selection changes it also sends selectionDidChange to its associations.

See also:  - endEditing, - redisplay, - markUndo, - setMarksEveryOperation:, - setUndoEnabled:

undo:

- undo:sender

This action method invokes undo and returns self.

Methods Implemented by the Delegate

controller:association:didEditObject:key:value:

- (void)controller:(EOController *)controller
association:(EOAssociation *)anAssociation
didEditObject:anEO
key:(NSString *)aKey
value:aValue

Sent from associationDidEdit: to inform the delegate that anAssociation has performed an edit.

controller:createObjectFailedForDataSource:

- (void)controller:(EOController *)controller 	    createObjectFailedForDataSource:dataSource

This method can be implemented to respond when the controller is unable to create an object for a data source. If the delegate does not implement this method, the controller will put up a panel to alert the user of the error. Otherwise, the delegate is responsible for notifying the user.

controller:didChangeDataSource:

- (void)controller:(EOController *)controller didChangeDataSource:(id <EODataSources>)aDataSource

Sent from setDataSource: to inform the delegate that controller's data source is now aDataSource.

controllerDidChangeSelection:

- (void)controllerDidChangeSelection:(EOController *)controller

Sent whenever controller's selection changes to inform the delegate of the change.

controller:didDeleteObject:

- (void)controller:(EOController *)controller didDeleteObject:anEO

Sent from any of the delete methods to inform the delegate that controller has deleted anEO.

controller:didDeleteObject:inDataSource:

- (void)controller:(EOController *)controller
didDeleteObject:anEO
inDataSource:aDataSource

Sent from saveToDataSource to inform the delegate that controller has deleted anEO from aDataSource.

controller:didFetchObjects:

- (void)controller:(EOController *)controller didFetchObjects:(NSArray *)objects

Sent from fetch to inform the delegate that controller has fetched the enterprise objects in objects from its data source.

controller:didInsertObject:

- (void)controller:(EOController *)controller didInsertObject:anEO

Sent from saveToObjects to inform the delegate that controller has inserted anEO.

controller:didInsertObject:inDataSource:

- (void)controller:(EOController *)controller
didInsertObject:anEO
inDataSource:aDataSource

Sent from saveToDataSource to inform the delegate that controller has inserted anEO into aDataSource.

controller:didRollbackDataSource:

- (void)controller:(EOController *)controller didRollbackDataSource:(id <EODataSources>)aDataSource

Sent from saveToDataSource to inform the delegate that controller has rolled back changes in aDataSource.

controllerDidSaveToDataSource:

- (void)controllerDidSaveToDataSource:(EOController *)controller

Sent from saveToDataSource to inform the delegate that controller has finished saving all operations to its data source. This method is only invoked if all operations were successfully saved.

controller:didSaveToObject:

- (void)controller:(EOController *)controller didSaveToObject:anEO

Sent from saveToObjects to inform the delegate that controller has saved edits to anEO.

controllerDidUndo:

- (void)controllerDidUndo:(EOController *)controller

Sent from undo to inform the delegate that controller has performed an undo operation.

controller:didUndoObject:

- (void)controller:(EOController *)controller didUndoObject:anEO

Sent from undo to inform the delegate that controller has undone changes to anEO.

controller:didUpdateObject:inDataSource:

- (void)controller:(EOController *)controller
didUpdateObject:anEO
inDataSource:aDataSource

Sent from saveToDataSource to inform the delegate that controller has updated anEO in aDataSource.

controller:failedToDeleteObject:inDataSource:

- (EODataSourceFailureResponse)controller:(EOController *)controller
failedToDeleteObject:anEO
inDataSource:aDataSource

Sent from saveToDataSource to inform the delegate that controller has failed to delete anEO from aDataSource. If the delegate returns EOContinueDataSourceFailureResponse controller continues saving other changes to the data source.

If the delegate returns EORollbackDataSourceFailureResponse controller sends rollback to its data source if the data source responds to that message. saveToDataSource then aborts and returns a failure result.

In rolling back the data source, the controller invokes the delegate methods controller:willRollbackDataSource: and controller:didRollbackDataSource:.

controller:failedToInsertObject:inDataSource:

- (EODataSourceFailureResponse)controller:(EOController *)controller
failedToInsertObject:anEO
inDataSource:aDataSource

Sent from saveToDataSource to inform the delegate that controller has failed to insert anEO into aDataSource. If the delegate returns EOContinueDataSourceFailureResponse controller continues saving other changes to the data source. If the delegate returns EORollbackDataSourceFailureResponse controller sends rollback to its data source if the data source responds to that message. saveToDataSource then aborts and returns a failure result.

In rolling back the data source, the controller invokes the delegate methods controller:willRollbackDataSource: and controller:didRollbackDataSource:.

controller:failedToUpdateObject:inDataSource:

- (EODataSourceFailureResponse)controller:(EOController *)controller
failedToUpdateObject:anEO
inDataSource:aDataSource

Sent from saveToDataSource to inform the delegate that controller has failed to update anEO in aDataSource. If the delegate returns EOContinueDataSourceFailureResponse controller continues saving other changes to the data source. If the delegate returns EORollbackDataSourceFailureResponse controller sends rollback to its data source if the data source responds to that message. saveToDataSource then aborts and returns a failure result.

In rolling back the data source, the controller invokes the delegate methods controller:willRollbackDataSource: and controller:didRollbackDataSource:.

controller:object:failedToPrepareForDataSource:

- (EODataSourceFailureResponse)controller:(EOController *)controller
object:anEO
failedToPrepareForDataSource:aDataSource

Sent from saveToDataSource when anEO returns NO from a prepareForDataSource message. If the delegate returns EOContinueDataSourceFailureResponse controller continues saving other changes to the data source. If the delegate returns EORollbackDataSourceFailureResponse controller sends rollback to its data source if the data source responds to that message. saveToDataSource then aborts and returns a failure result.

controller:saveObjectsFailedForDataSource:

- (void)controller:(EOController *)controller
saveObjectsFailedForDataSource:aDataSource

Sent from saveToDataSource to inform the delegate that aDataSource returned NO from a saveObjects message.

controller:sortObjects:

- (void)controller:(EOController *)controller sortObjects:(NSMutableArray *)objects

If the delegate implements this method,it is responsible for sorting the given object array.  If the delegate does not implement this method and a sortOrdering has been specified, the controller will sort the objects itself using [objects sortUsingKeyOrderArray:[self sortOrdering]].

controller:willDeleteObject:

- (BOOL)controller:(EOController *)controller willDeleteObject:anEO

Sent from any of the delete methods to inform the delegate that controller will delete anEO. If the delegate returns NO the deletion isn't performed and saveToObjects is aborted; if the delegate returns YES the deletion proceeds.

controller:willDeleteObject:inDataSource:

- (EODataSourceOperationDelegateResponse)controller:(EOController *)controller
willDeleteObject:anEO
inDataSource:aDataSource

Sent from saveToDataSource to inform the delegate that controller will delete anEO from aDataSource. If the delegate returns EODiscardDataSourceOperation the deletion isn't performed (though saveToDataSource continues for other operations); if the delegate returns EOPerformDataSourceOperation the deletion proceeds. A return value of EOContinueDataSourceOperation indicates that the operation is not to be performed, but should be left on the operation stack to be performed on the next save. A return value of EORollbackDataSourceOperation indicates that the current saveToDataSource operation should be aborted and all changes rolled back.

controllerWillDiscardEdits:

- (BOOL)controllerWillDiscardEdits:(EOController *)controller

Sent from isDiscardAllowed to inform the delegate that controller is about to discard pending edits. If the delegate doesn't implement this method controller opens an attention panel warning the user that edits may be discarded. If the delegate returns NO then isDiscardAllowed returns NO; if the delegate returns YES then isDiscardAllowed proceeds.

If the delegate wants to make sure edits are preserved it can explicitly send saveToObjects to controller.

controllerWillDiscardOperations:

- (BOOL)controllerWillDiscardOperations:(EOController *)controller

Sent from isDiscardAllowed to inform the delegate that controller is about to discard pending operations destined for its data source. If the delegate doesn't implement this method controller opens an attention panel warning the user that updates may be discarded. If the delegate returns NO then isDiscardAllowed returns NO; if the delegate returns YES then isDiscardAllowed proceeds.

If the delegate wants to make sure updates are preserved it can explicitly send saveToDataSource to controller.

controllerWillFetch:

- (BOOL)controllerWillFetch:(EOController *)controller

Invoked from fetch to inform the delegate that controller is about to fetch. If the delegate returns NO the fetch is aborted; if the delegate returns YES the fetch proceeds.

controller:willInsertObject:atIndex:

- (BOOL)controller:(EOController *)controller
willInsertObject:anEO
atIndex:(unsigned int)anIndex

Sent from insertObject:atIndex: to inform the delegate that controller will insert anEO into its array of objects at anIndex. If the delegate returns EODiscardDataSourceOperation the insertion is aborted; if the delegate returns EOPerformDataSourceOperation the insertion proceeds. A return value of EOContinueDataSourceOperation indicates that the operation is not to be performed, but should be left on the operation stack to be performed on the next save. A return value of EORollbackDataSourceOperation indicates that the current saveToDataSource operation should be aborted and all changes rolled back.

The delegate may modify anEO, usually by setting its primary key to a unique value.

controller:willInsertObject:inDataSource:

- (EODataSourceOperationDelegateResponse)controller:(EOController *)controller
willInsertObject:anEO
inDataSource:aDataSource

Sent from saveToDataSource to inform the delegate that controller will insert anEO into aDataSource. If the delegate returns EODiscardDataSourceOperation the insertion isn't performed (though saveToDataSource continues for other operations); if the delegate returns EOPerformDataSourceOperation the insertion proceeds. A return value of EOContinueDataSourceOperation indicates that the operation is not to be performed, but should be left on the operation stack to be performed on the next save. A return value of EORollbackDataSourceOperation indicates that the current saveToDataSource operation should be aborted and all changes rolled back.

controller:willRollbackDataSource:

- (void)controller:(EOController *)controller willRollbackDataSource:(id <EODataSources>)aDataSource

Sent from saveToDataSource to inform the delegate that controller will roll back changes in aDataSource. The delegate can't prevent this operation, but may take whatever action it needs based on this information.

controller:willSaveEdits:toObject:

- (NSDictionary *)controller:(EOController *)controller
willSaveEdits:(NSDictionary *)newValues
toObject:anEO

Sent from saveToObjects to inform the delegate that controller will save edits to anEO. newValues is a dictionary of key-value pairs whose keys are the names of properties belonging to anEO and whose values are the new values anEO will be given for those properties. The delegate can return the values as they are, or can return a substitute set of values to apply to the object. If the delegate returns nil the save isn't performed and saveToObjects is aborted.

controllerWillSaveToDataSource:

- (BOOL)controllerWillSaveToDataSource:(EOController *)controller

Sent from saveToDataSource to inform the delegate that controller will saves changes to its data source. If the delegate returns NO the save is aborted; if the delegate returns YES the save proceeds.

controllerWillUndo:

- (BOOL)controllerWillUndo:(EOController *)controller

Sent from undo to inform the delegate that controller will undo changes. If the delegate returns NO the undo operation is aborted; if the delegate returns YES the undo operation proceeds.

controller:willUndoObject:

- (BOOL)controller:(EOController *)controller willUndoObject:anEO

Sent from undo to inform the delegate that controller will undo changes previously made to anEO. If the delegate returns NO the undo operation for anEO only is aborted (the larger undo operation proceeds); if the delegate returns YES the undo operation for anEO proceeds.

controller:willUpdateObject:inDataSource:

- (EODataSourceOperationDelegateResponse)controller:(EOController *)controller
willUpdateObject:anEO
inDataSource:aDataSource

Sent from saveToDataSource to inform the delegate that controller will update anEO in aDataSource. If the delegate returns EODiscardDataSourceOperation the update isn't performed (though saveToDataSource continues for other operations); if the delegate returns EOPerformDataSourceOperation the update proceeds. A return value of EOContinueDataSourceOperation indicates that the operation is not to be performed, but should be left on the operation stack to be performed on the next save. A return value of EORollbackDataSourceOperation indicates that the current saveToDataSource operation should be aborted and all changes rolled back.